This section details the final steps that you must take to produce a stand-alone, double-clickable application. The requirements for an application using Tools Plus libraries are nearly identical to those of ordinary Macintosh applications, except that the SIZE resource has some very specific needs. It is assumed that by the time you address these concerns, you have already written and debugged an application within your development environment and that you are ready to make it a stand-alone application.
All the work encompassed in this section requires that you use a resource editor such as Apple’s ResEdit to create and/or modify resources. The Symantec and Metrowerks development environments allow you to use a resource file as part of your project. That resource file is automatically merged into your compiled code when you build your project. Therefore we recommend you create and save these resources in a separate resource file and allow your development environment to merge them with your application (instead of manually adding them to your compiled application).
Completing your application involves making some decisions, then creating the appropriate resources. The table below summarizes the various tasks and their significance to your final application.
The Macintosh’s Finder displays an application and its related files as icons. In order for the Finder to do this, it needs to know what each icon looks like. Without this information, your application will have the “generic application” icon (diamond with a hand holding a pen) and its related files will have the “generic document” icon (blank page with corner folded down).
At the very least, you will need to create a large (32x32 bit) black and white icon (ICN#) for your application, and one for each type of document it creates. You should also consider creating equivalent small (16x16 bit) black and white icons (ics#), because the Finder displays these miniatures when a disk’s or folder’s view is set to “small icon,” or when System 7 displays lists with icons.
System 7 can display your application’s icons in color, so you can optionally include color icons as equivalents for the black and white ones. The icl8 and icl4 icon types are large icons using 8 bits (256 colors) and 4 bits (16 colors) respectively. Small color icons can also be created as ics8 and ics4 type icons. Later, the “bundle” describes how to integrate the icon resources into your finished application.
Icon Family
```````````
When a specific icon ID number is shared by two or more icon types, those related icons are called an “icon family.” The icon family with an ID of 128 is usually the icon that depicts your application. Your application’s document icons would likely be numbered 129 and up. When you create icons, remember to use ID numbers 128 or higher. The rest are reserved numbers.
Note: When creating icl8 and ics8 icons with ResEdit, you have a choice
of two color palettes: “Apple icon colors” or “Standard 256
colors.” Use the Apple icon colors, since they will guarantee
that your icon can be selected (darkened) properly.
File Types, Creators, and the Application Signature
On the Macintosh, all files (including application, desk accessories, documents, etc.) have a file type and a creator code. Both of these items are always four characters long, allowing any visible or invisible characters and spaces. The file type tells the Macintosh what the file contains. Your application will always have a file type of ‘APPL.’ You can define your own file types for the documents created by your application if they don’t fit into any of the existing general types as follows:
APPL Launchable application
DFIL File for sorting DAs
DRVR Driver
FFIL File for sorting fonts
INIT System extension
PICT QuickDraw picture
PRER Printer driver
RDEV Chooser extension
TEXT Stream of ASCII characters
adev Network extension
appe Background-only application
cdev Control panel
edtp Edition for sharing graphics
edts Edition for sharing sound
edtt Edition for sharing text
ffil Font
ifil Script system resources
kfil Keyboard layout
pref Preferences file
qery Query document (databases)
scri System extension for scripting
sfil Sound
tfil TrueType font
ttro TeachText read-only file
zsys A system file
Later, the “bundle” describes how to integrate file type(s) into your finished application.
Signature (the Creator code)
````````````````````````````
Each application must have a unique, four character signature. A signature is often called a creator code because it answers the question “who created me” for every document on a Macintosh (an application is considered to be its own creator). Your application’s signature will be used as the creator code for all the documents it creates.
The Finder makes an association between each application and its related documents by using the application’s signature. When a document is opened by the Finder, it knows which application created the file and automatically launches that application.
Notice that some file types can be opened by several applications. If you double-click a ‘TEXT’ file, it will be opened by the application that launched it (because the Finder recognizes the creator for the file is identical to the parent application’s signature). However, just about any word processor can open a ‘TEXT’.
In THINK Pascal, you set your application’s type and creator by using the Project menu’s “Set project Type” command. Later, the “bundle” describes how to integrate the signature into your finished application.
Note: Apple reserves the use of all file types and signatures (creator
codes) whose names contain only lowercase letters, and those that
contain only non-alphabetic characters. Your file types and
signatures must contain at least one uppercase letter. Since the
system software never displays the file type or signature to
users, these codes don’t have to be meaningful to anyone but you.
All file types and signatures must be registered with Apple to
guarantee uniqueness and prevent conflicts between applications.
Warning: When deciding upon a signature for your application, be careful
to avoid signatures that are identical to any existing resource
type, such as ‘ICON’ or ‘STR ’. An owner resource must be
created with a type that matches your application’s signature,
and if it coincides with existing resources types, conflicts
may arise. For a comprehensive list of resource codes, please
refer to the ResEdit Reference manual, or contact Apple.
Bundle
``````
The BNDL resource, which is simply called the “bundle,” is used to “bundle up” several related resources that are needed to define the association between your application, its documents, and the icons displayed by the Finder. If you use ResEdit to create the BNDL resource, you will be presented with a template that lets you create and maintain the BNDL resource.
Enter the four character signature you have selected for your application.
Next, use the Resource menu’s “Create New File Type” command to create a new line. Enter the file type. Note that the first line should have a type of ‘APPL’ (application). Double-click its “Finder Icons” section and you will be presented with a list of icons that you created earlier in the “Application Icons” section of this chapter. Select the icon you want to use to represent the specified file type. Repeat this for each file type that is supported by your application.
The last thing you must do to complete the bundle is to set the “bundle bit.” The bundle bit tells the Finder that your application has a bundle present. In THINK Pascal, you set the bundle bit by using the Project menu’s “Set project Type” command, then building your application. The bundle bit is set automatically in THINK C/C++ and Metrowerks compilers.
When creating the BNDL resource, ResEdit automatically creates several other supporting resources. One FREF resource (Finder REFerence) is created for each file type. An “Owner Resource” is also created (ID=0). Its resource type matches your application’s signature. The owner resource is essentially a string resource that lets you enter a comment that is displayed as version information in the Finder’s “Get Info” box (providing you don’t create ‘vers’ resources).
Note: If you change your application’s icons, you will have to rebuild
the desk top file to force the Finder to use your new icons. To
rebuild the desk top, restart your Macintosh while holding the
option and command keys down, and continue to hold them until you
see a dialog that asks you if you want to rebuild your desk top.
Click the OK button to start rebuilding.
A similar problem sometimes occurs when an application is
copied to a disk using an installer or decompression program.
These kinds of programs may not have the intelligence to update
the desk top file like the Macintosh’s Finder does.
Version
```````
Your application can display some descriptive information in the Finder’s “Get Info” box by having ‘vers’ resources. The two vers resources you can include in your applications are:
ID=2 Application info displayed beneath the file name (i.e., Tools
Plus Library (1 of 3) )
By using vers resources, any file can bear version information, including documents created by your application.
mstr Resources
``````````````
This section describes how System 5 and 6’s MultiFinder and System 7 automatically interact with your application’s menus if your application does not support high-level events (also called Apple Events). You should set the appropriate bit in your application’s ‘SIZE’ resource to indicate if it supports Apple Events or not.
Both MultiFinder (running under System 5 or 6) and System 7 can automatically interact with your application through its menus. If your application is running while the user double-clicks (or select-opens) one of your application’s documents from the Finder, the affected document is automatically opened by your application. Also, if the user selects the Special menu’s Restart or Shut Down command while your application is running, it is instructed to quit.
In both these cases, the system simulates the selection of a menu item. Typically applications have a File menu with an item named “Open…” (including the ellipsis, the Option-; character), and the last item named “Quit”. In the case of opening a document, PollSystem returns a doMenu event to your application indicating that the File menu’s “Open…” command was selected, in which case your application would do whatever is appropriate, like display an SFGetFile dialog to let the user choose which file to open. The system fools your application into thinking that the double-clicked file was selected from an SFGetFile dialog (which is not actually displayed). When the user selects Restart or Shut Down, PollSystem returns a doMenu event to your application indicating that the File menu’s “Quit” command was selected, in which case your application would do whatever is appropriate, such as asking if open documents should be saved before quitting.
If your application does not [1] open files by using the File menu’s “Open…” command, or [2] quit by using the File menu’s “Quit” command, these functions can be remapped to other menu items by including ‘mstr’ resources in your application. Each mstr resource is a Pascal string (byte-0 is the length byte) that tells the Macintosh which menu and menu item to use in place of the standard ones:
mstr ID=100 Name of the menu containing the equivalent of the
“Quit” command
mstr ID=101 Name of the menu item that is the equivalent of the
“Quit” command
mstr ID=102 Name of the menu containing the equivalent of the
“Open…” command
mstr ID=103 Name of the menu item that is the equivalent of the
“Open…” command
SIZE Resource
`````````````
If your application is going to run under MultiFinder or System 7, it needs a SIZE resource. ResEdit has a resource template for the SIZE resource, which lets you set various values in the resource to specify how your application behaves in a multi-tasking environment.
You will create a single resource with an ID of -1, but be aware that the Macintosh may clone (make a duplicate with a possible minor variation) your SIZE resource in your stand-alone application under certain conditions. This is described later.
The SIZE resource is comprised of sixteen bits that can be set to a value of 0 or 1, and two long integers. Tools Plus requires that some of these items be set to a specific value while others depend upon how you want your application to behave. The table below details the SIZE resource.
Although you need to create only one SIZE resource (ID=-1), the Macintosh may make clones of it when the user makes changes in the Finder’s “Get Info” box. When the user makes changes in the “Get Info” box, the Macintosh clones (makes a copy of the SIZE resource with ID=-1) and lets the user makes changes to the “Size” and “Min size” fields of the clone. You only need to be concerned with this if you want to preset your application’s memory requirements to something other than the recommended limits defined by your original SIZE resource.
The table below describes the contents of the “Size” and “Min size” fields for the original SIZE resource, as well as any clones that may be created by the Macintosh.
